NSDL PAN Direct API

The following document highlights the details of the NSDL PAN Direct API.

API Usage Guidelines

The NSDL PAN Direct API is available exclusively to Regulated Entities (REs) with valid regulatory licenses in India. Data access and processing must remain within your licensed Indian entity, and all data must be stored within Indian geography only. Access from servers located outside India is not permitted.

If you have questions about these requirements or need clarification on your current access, please contact our team at HyperVerge.

API Description

Objective

The NSDL PAN Direct API verifies PAN authenticity and status against official government records.

Input	Output
The user's PAN, full name, father's name, and date of birth	The PAN status, name match verification, date of birth match verification, and seeding status

API URL

https://ind-engine.thomas.hyperverge.co/v1/NSDLPanVerificationDirect

API Endpoint

v1/NSDLPanVerificationDirect

Overview

The NSDL PAN Direct API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should send all data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the NSDL PAN Direct API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the NSDL PAN Direct API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
pan	Mandatory	string	The unique 10-character alphanumeric Permanent Account Number	'CCCCCDDDDC' format 'C' represents any Latin letters (A to Z), and 'D' represents Arabic numerals (0-9)	Not Applicable
name	Mandatory	string	The full name as it appears on the PAN card	Not Applicable	Not Applicable
dob	Mandatory	string	The date of birth of the PAN holder	DD/MM/YYYY	Not Applicable
fatherName	Optional	string	The full father's name as it appears on the PAN card	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the NSDL PAN Direct API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/NSDLPanVerificationDirect' \
--header 'Content-Type: application/json' \
--header 'appid: <Enter_the_appId_Shared_by_HyperVerge>' \
--header 'appkey: <Enter_the_appKey_shared_by_HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--data '{
  "pan": "<Enter_the_PAN>",
  "name": "<Enter_the_Name>",
  "fatherName": "<Enter_the_Father_Name>",
  "dob": "<Enter_the_DOB>"
}'

Success Response

The following code snippet demonstrates a success response from the NSDL PAN Direct API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "pan": "<pan>",
        "panStatus": "<panStatus>",
        "name": "<name>",
        "fathername": "<fathername>",
        "dob": "<dob>",
        "seedingStatus": "<seedingStatus>"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the NSDL PAN Direct API:

Parameter	Type	Description
status	string	The status of the API response indicating success or failure
statusCode	integer	The HTTP status code for the response
result	object	The JSON object containing the PAN verification details
pan	string	The full Permanent Account Number provided in the input and verified against official records
panStatus	string	The status indicating whether the PAN exists and is valid as per the official government database, for example; "Existing and Valid"
name	string	The match status indicating whether the name provided in the request matches the name linked to the PAN
fathername	string	The match status indicating whether the father's name provided in the request matches the father's name linked to the PAN
dob	string	The match status confirming whether the provided Date of Birth matches the DOB associated with the PAN
seedingStatus	string	The status indicating whether the PAN is currently active and linked to the government systems, for example, Operative PAN
metaData	object	The JSON object containing request and transaction identifiers
requestId	string	The unique identifier for the API request
transactionId	string	The unique identifier for the customer journey

Failure Response

The following code snippet demonstrates a failure response from the NSDL PAN Direct API:

{
    "status": "failure",
    "statusCode": 400,
    "message": "PAN Number invalid (too long, null, or special characters)"
}

Error Responses

The following are some error responses from the NSDL PAN Direct API:

Invalid PAN Number

{
    "message": "PAN Number invalid (too long, null, or special characters)",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid User ID or Certificate

{
    "message": "User ID does not exist in database, Wrong certificate used, or ID is invalid",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Private Key or Certificate

{
    "message": "Incorrect private key or certificate are used for signing",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Name

{
    "message": "Name of PAN holder is invalid (length or special chars)",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Father's Name

{
    "message": "Father's name is invalid (length or special chars)",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Date of Birth Format

{
    "message": "Date of Birth format is incorrect it should be separated with slash (/) and in format of (DD/MM/YYYY) or Value is Null",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Transaction ID

{
    "message": "Transaction ID invalid (too long or null)",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Authentication Failure

{
    "message": "Authentication Failure",
    "statusCode": 401,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

User Not Authorized

{
    "message": "User not authorized",
    "statusCode": 403,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

User Validity Expired

{
    "message": "User validity has expired",
    "statusCode": 403,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Certificate Revocation List Expired

{
    "message": "Certificate Revocation List issued by Certifying Authorities is expired",
    "statusCode": 403,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

User ID Deactivated

{
    "message": "User ID Deactivated",
    "statusCode": 403,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Duplicate Transaction ID

{
    "message": "Duplicate Transaction ID entered",
    "statusCode": 409,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

System Error

{
    "message": "System Error",
    "statusCode": 500,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

System Failure

{
    "message": "System Failure or common error message for request",
    "statusCode": 500,
    "status": "failure"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	PAN Number invalid (too long, null, or special characters)	The request contains an invalid PAN number that is either too long, null, or contains special characters	Ensure the PAN number is exactly 10 characters and contains only alphanumeric characters
400	User ID does not exist in database, Wrong certificate used, or ID is invalid	The request contains an invalid user ID, wrong certificate, or the ID does not exist in the database	Verify and provide a valid user ID and certificate
400	Incorrect private key or certificate are used for signing	The request uses an incorrect private key or certificate for signing	Verify and provide the correct private key and certificate for signing
400	Name of PAN holder is invalid (length or special chars)	The request contains an invalid name that might contain special characters	Ensure the entered name does not contain special characters
400	Father's name is invalid (length or special chars)	The request contains an invalid father's name that might contain special characters	Ensure the father's name does not contain special characters
400	Date of Birth format is incorrect it should be separated with slash (/) and in format of (DD/MM/YYYY) or Value is Null	The request contains an invalid date of birth format or a null value	Ensure the date of birth is in DD/MM/YYYY format separated with slash (/)
400	Transaction ID invalid (too long or null)	The request contains an invalid transaction ID that is either too long or null	Ensure the transaction ID is within the allowed length and is not null
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid appId and appKey credentials
401	Authentication Failure	The request contains an invalid certificate for authentication	Verify and provide a valid certificate for authentication
403	User not authorized	The user ID is not registered with Protean	Contact the HyperVerge team to register the user ID with Protean
403	User validity has expired	The validity period for the user ID has expired	Contact the HyperVerge team to renew the user ID validity
403	Certificate Revocation List issued by Certifying Authorities is expired	The certificate revocation list has expired	Contact the HyperVerge team to update the certificate revocation list
403	User ID Deactivated	The user ID has been deactivated	Contact the HyperVerge team to reactivate the user ID
409	Duplicate Transaction ID entered	The request uses a transaction ID that has already been used for another request	Ensure each request uses a unique transaction ID
500	System Error	The request encountered an internal system error at Protean	Retry the request after some time or contact the HyperVerge team if the issue persists
500	System Failure or common error message for request	The request encountered a system failure or a common error	Retry the request after some time or contact the HyperVerge team if the issue persists